SDK iOS

Vue d’ensemble

Le SDK iOS natif de WebAR³ VPS localise les utilisateurs dans vos cartes VPS grâce au suivi ARKit. Le XCFramework est compatible avec UIKit, RealityKit et SwiftUI. Suivez le déroulé Immersal : prérequis, installation, autorisations puis initialisation du service.

Prérequis

• iOS 12.0 ou version ultérieure
• Xcode 12+ avec Swift 5
• Appareil compatible ARKit (le simulateur n’est pas pris en charge)

Options d’installation

Via Swift Package Manager

1. Dans Xcode, ouvrez File → Add Packages….
2. Entrez https://github.com/WebAR-Studio/was-vps-ios.git.
3. Sélectionnez la branche ou le tag souhaité puis ajoutez le package à votre cible.

Intégration manuelle

1. Clonez le dépôt :

   git clone https://github.com/WebAR-Studio/was-vps-ios.git

2. Glissez WASVPS.xcframework dans votre projet.
3. Dans General → Frameworks, Libraries, and Embedded Content, vérifiez que le framework est bien intégré.

Configurer les autorisations

Ajoutez les textes d’usage caméra et localisation dans Info.plist pour déclencher les invites système.

<key>NSCameraUsageDescription</key>
<string>L’app nécessite la caméra pour afficher du contenu en réalité augmentée.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>L’app utilise votre position pour placer précisément le contenu AR.</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>VPSLocalization</key>
    <string>Active une localisation précise pour des expériences AR fiables.</string>
</dict>

Initialiser le VPS

VPSBuilder.initializeVPS crée une instance de VPSService. Passez l’ARSession, votre API key et les Location ID.

Besoin d’une API key ? Vous pouvez l’obtenir sur space.web-ar.studio ou en écrivant à support@webar3.com / support@web-ar.studio.

import ARKit
import WASVPS

final class VPSDemoController: UIViewController, ARSCNViewDelegate {
    @IBOutlet private weak var sceneView: ARSCNView!
    private var configuration: ARWorldTrackingConfiguration?
    private var vps: VPSService?

    override func viewDidLoad() {
        super.viewDidLoad()
        sceneView.delegate = self
        sceneView.scene = SCNScene()

        configuration = VPSBuilder.getDefaultConfiguration()

        VPSBuilder.initializeVPS(
            arSession: sceneView.session,
            apiKey: "your-api-key",
            locationIds: ["your-location-id"],
            url: "https://was-vps.web-ar.xyz/vps/api/v3",
            gpsUsage: false,
            delegate: self
        ) { service in
            self.vps = service
            self.vps?.start()
        }
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        if let configuration { sceneView.session.run(configuration) }
    }

    func renderer(_ renderer: SCNSceneRenderer, updateAtTime time: TimeInterval) {
        vps?.frameUpdated()
    }
}

extension VPSDemoController: VPSServiceDelegate {
    func positionVPS(pos: ResponseVPSPhoto) {
        print("Localized pose:", pos)
    }

    func error(err: NSError) {
        print("VPS error:", err)
    }

    func sending(requestData: UploadVPSPhoto?) {
        print("Sending localization request…")
    }
}

Arrêtez le service dans sessionWasInterrupted et relancez-le dans sessionInterruptionEnded.

RealityKit

En RealityKit, transférez chaque frame via ARSessionDelegate :

func session(_ session: ARSession, didUpdate frame: ARFrame) {
    vps?.frameUpdated()
}

Les méthodes de cycle de vie (start, stop, clearCustomLocPos) restent identiques à SceneKit.

SwiftUI

Encapsulez ARSCNView ou ARView dans un UIViewRepresentable/UIViewControllerRepresentable. Stockez VPSService dans un ViewModel et déclenchez start()/stop() depuis les contrôles SwiftUI.

Contrôles avancés

• setCustomLocPosForFirstRequest définit une pose connue avant la première requête.
• Le paramètre url de initializeVPS permet de cibler un autre endpoint (par défaut https://was-vps.web-ar.xyz/vps/api/v3).
• Activez gpsUsage pour inclure les coordonnées de l’appareil dans les requêtes.

Dépannage

• VPSBuilder.getDefaultConfiguration() renvoie nil ? L’appareil ne supporte pas ARKit.
• Pas de callbacks ? Vérifiez que frameUpdated() est appelé à chaque frame et que l’API key et les Location ID sont valides.
• Jetez un œil au dossier /examples pour des implémentations complètes UIKit, RealityKit et SwiftUI.